XQuery API for Java
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
top
The XQJ API enables Java programmers to execute XQuery against an XML data source (e.g. an XML database) while reducing or eliminating vendor lock in.
The XQJ API provides Java developers with an interface to the XQuery Data Model.cite-ref-xquerydatamodel-1-0[1] Its design is similar to the JDBC API which has a client/server feel and as such lends itself well to Server-based XML Databases and less well to client-side XQuery processors, although the "connection" part is a very minor part of the entire API. Users of the XQJ API can bind Java values to XQuery expressions, preventing code injection attacks.cite-ref-2[2] Also, multiple XQuery expressions can be executed as part of an atomic transaction.
Contents
• Examples
• License
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
History and implementation
The XQuery API for Java was developed at the Java Community Process as JSR 225. It had some big technology backers such as Oracle,cite-ref-3[3]cite-ref-xqj-completed-paper-4-0[4]cite-ref-ibm-and-oracle-submit-jsr-5-0[5]cite-ref-early-look-at-xqj-paper-6-0[6] IBM,cite-ref-ibm-and-oracle-submit-jsr-5-1[5]cite-ref-early-look-at-xqj-paper-6-1[6] BEA Systems,cite-ref-7[7] Software AG,cite-ref-8[8] Intel, Nokia and DataDirect.cite-ref-xqj-completed-paper-4-1[4]
Version 1.0 of the XQuery API for Java Specification was released on June 24, 2009,cite-ref-9[9] along with JavaDocs, a reference implementation and a TCK (Technology Compatibility Kit) which implementing vendors must conform to.
The XQJ classes are contained in the Java package javax.xml.xquery
There is no (visible) activity to create a version of XQJ that provides support for XQuery 3.0 or 3.1, for example by providing Java bindings for additions to the data model such as functions, arrays, or maps.
Functionality
XQJ allows multiple implementations to exist and be used by the same application.
• XQExpression – the expression is sent to the XQuery processor every time.
• XQPreparedExpression – the expression is cached and the execution path is pre-determined allowing it to be executed multiple times in an efficient manner.
XQuery expressions return a result sequence of XDMcite-ref-xquerydatamodel-1-1[1] items which in XQJ are represented through the XQResultSequence interface. The programmer can use an XQResultSequence to walk over individual XDMcite-ref-xquerydatamodel-1-2[1] items in the result sequence. Each item in the sequence has XDMcite-ref-xquerydatamodel-1-3[1] type information associated with it, such as its node type e.g. element(), document-node() or an XDM atomic type such as xs:string, xs:integer or xs:dateTime. XDM type information in XQJ can be retrieved via the XQItemType interface.
Examples
Basic example
The following example illustrates creating a connection to an XML Database, submitting an XQuery expression, then processing the results in Java. Once all of the results have been processed, the connection is closed to free up all resources associated with it.
// Create a new connection to an XML database
XQConnection conn = vendorDataSource.getConnection("myUser", "myPassword");
XQExpression expr = conn.createExpression(); // Create a reusable XQuery Expression object
XQResultSequence result = expr.executeQuery(
"for $n in fn:collection('catalog')//item " +
"return fn:data($n/name)"); // execute an XQuery expression
// Process the result sequence iteratively
while (result.next()) {
// Print the current item in the sequence
System.out.println("Product name: " + result.getItemAsString(null));
}
// Free all resources created by the connection
conn.close();
Binding a value to an external variable
XQExpression expr = conn.createExpression();
// The XQuery expression to be executed
String es = "declare variable $x as xs:integer external;" +
" for $n in fn:collection('catalog')//item" +
" where $n/price <= $x" +
" return fn:data($n/name)";
// Bind a value (21) to an external variable with the QName x
expr.bindInt(new QName("x"), 21, null);
// Execute the XQuery expression
XQResultSequence result = expr.executeQuery(es);
// Process the result (sequence) iteratively
while (result.next()) {
// Process the result ...
}
Default data type mapping
| Java Datatype | Default XQuery Data Type(s) |
|---|---|
| boolean | xs:boolean |
| byte | xs:byte |
| byte[] | xs:hexBinary |
| double | xs:double |
| float | xs:float |
| int | xs:int |
| long | xs:long |
| short | xs:short |
| Boolean | xs:boolean |
| Byte | xs:byte |
| Float | xs:float |
| Double | xs:double |
| Integer | xs:int |
| Long | xs:long |
| Short | xs:short |
| String | xs:string |
| BigDecimal | xs:decimal |
| BigInteger | xs:integer |
| Duration | xs:dayTimeDuration if the Duration Object's state is xs:dayTimeDuration |
| Duration | xs:yearMonthDuration if the Duration Object's state is xs:yearMonthDuration |
| Duration | xs:duration if the Duration Object's state is xs:duration |
| XMLGregorianCalendar | xs:date if the XMLGregorianCalendar Object's state is xs:date |
| XMLGregorianCalendar | xs:dateTime if the XMLGregorianCalendar Object's state is xs:dateTime |
| XMLGregorianCalendar | xs:gDay if the XMLGregorianCalendar Object's state is xs:gDay |
| XMLGregorianCalendar | xs:gMonth if the XMLGregorianCalendar Object's state is xs:gMonth |
| XMLGregorianCalendar | xs:gMonthDay if the XMLGregorianCalendar Object's state is xs:gMonthDay |
| XMLGregorianCalendar | xs:gYear if the XMLGregorianCalendar Object's state is xs:gYear |
| XMLGregorianCalendar | xs:gYearMonth if the XMLGregorianCalendar Object's state is xs:gYearMonth |
| XMLGregorianCalendar | xs:time if the XMLGregorianCalendar Object's state is xs:time |
| QName | xs:QName |
| Document | document-node(element(*, xs:untyped)) |
| DocumentFragment | document-node(element(*, xs:untyped)) |
| Element | element(*, xs:untyped) |
| Attr | attribute(*, xs:untypedAtomic) |
| Comment | comment() |
| ProcessingInstruction | processing-instruction() |
| Text | text() |
Known implementations
Native XML databases
The following is a list of Native XML Databases which are known to have XQuery API for Java implementations.
• Taminocite-ref-17[17]
Relational databases
DataDirect provide XQJ adapters for relational databases, by translating XQuery code into SQL on the fly, then converting SQL result sets into a format suitable for XQJ to process further. The following is a couple of known implementations.
• Oracle DB (Not XDB)
• IBM Db2
• Informix
• MySQL
Non-database implementations
The following is a list of non-database XQuery processors which provide an XQuery API for Java interface (typically allowing query against documents parsed from XML in filestore, and held in memory as DOM or similar trees).
• MXQuery
• Oracle XQuery Processor cite-ref-19[19]
License
The specification is marked as "Copyright © 2003, 2006 - 2009 Oracle. All rights reserved."
The specification contains two separate licenses: a "specification license" and a "reference implementation license".
The specification license allows free copying of the specification provided that copyright notices are retained; it also grants a license to create and distribute an implementation of the specification provided that it fully implements the entire specification, that it does not modify or extend any interfaces, and that it passes the compatibility tests.
This provision has caused some controversy. Firstly, it is not universally accepted that implementing a published specification is something that requires a license (that is, that copyright law would disallow this in the absence of a license).cite-ref-20[20]cite-ref-21[21] Secondly, the license does not meet the criteria to qualify as an open source license (see Open Source Definition), because of the ban on making extensions and modifications. This has led some open source enthusiasts to challenge whether XQJ implementations can ever be considered truly open source.
The license for the reference implementation is a fairly conventional BSD-style open source license.
References
cite-note-xquerydatamodel-11. ↑ XQuery 1.0 and XPath 2.0 Data Model (XDM)
cite-note-22. ↑ Binding Java Variables
cite-note-xqj-completed-paper-44. ↑ XQJ - XQuery Java API is Completed, Marc Van Cappellen, Zhen Hua Liu, Jim Melton and Maxim Orgiyan Archived 28 July 2012 at the Wayback Machine
cite-note-ibm-and-oracle-submit-jsr-55. ↑ IBM and Oracle Submit XQuery API for Java (XQJ) Java Specification Request.
cite-note-early-look-at-xqj-paper-66. ↑ An Early Look at XQuery API for Java (XQJ) - Andrew Eisenberg, IBM and Jim Melton, Oracle Archived 28 July 2012 at the Wayback Machine
cite-note-77. ↑ The BEA Streaming XQuery Processor
cite-note-88. ↑ XQJ Interface for Tamino Native XML Database Archived 30 May 2013 at the Wayback Machine
cite-note-99. ↑ JSR-000225 XQuery API for Java (Final Release)
cite-note-xquf-1010. ↑ XQuery Update Facility
cite-note-1111. ↑ XQuery Full Text
cite-note-1212. ↑ MarkLogic XQJ API
cite-note-1313. ↑ eXist XQJ API
cite-note-1414. ↑ BaseX XQJ API
cite-note-1515. ↑ Sedna XQJ API
cite-note-1616. ↑ Oracle XML DB Support for XQJ
cite-note-1717. ↑ Software AG - Working with the CentraSite XQJ Interface
cite-note-1818. ↑ Zorba 2.5 ships with a long awaited XQJ binding, 14 June 2012
cite-note-1919. ↑ Oracle XML Developer's Kit (XDK) provides a standalone XQuery 1.0 processor for use by Java applications.
cite-note-2020. ↑ "Open Standards" (PDF). Archived from the original (PDF) on 4 March 2016. Retrieved 7 September 2023.
cite-note-2121. ↑ "Groklaw - Oracle v. Google - Understanding the Copyright Issue with API Specifications". www.groklaw.net. Archived from the original on 5 May 2012.
External links
• Javadoc for XQJ
• XQJ Tutorial
• Building Bridges from Java to XQuery, Charles Foster. XML Prague 2012 (Prezi Presentation)
• Java Integration of XQuery, Hans-Jürgen Rennau. Balisage 2010
• Orbeon Forms using XQJ Archived 22 November 2012 at the Wayback Machine
• Spring Integration XQuery Support
• XQS: XQuery for Scala (Sits on top of XQJ)
• IntelliJ XQuery Support plugin